home *** CD-ROM | disk | FTP | other *** search
/ TPUG - Toronto PET Users Group / TPUG Users Group CD / TPUG Users Group CD.iso / AMIGA / AMICUS / AMICUS05.ADF / IFF / iffabout < prev    next >
Text File  |  1986-04-20  |  9KB  |  204 lines
  1.  
  2.           Overview of IFF example source files
  3.                   Feb. 4, 1986
  4.  
  5.  
  6. This source code is distributed as public domain software.
  7. Use it to help write robust IFF-compatible programs.
  8.  
  9. Caveat: Electronic Arts developed this code, and is releasing it to
  10. promote the success of the Amiga.  EA does not have the resources 
  11. to supply support for this code.
  12.  
  13.                    ----->>>>     <<<<-----
  14. COMMODORE NOTICE: Not all of these files have been uploaded to the
  15. Bulletin board. These files will be uploaded over the next week
  16. until the entire disk is here (executables and object files 
  17. excluded). If you would like to see a file that is not here, please
  18. drop a note to askamiga and we will put that file up ASAP. Thank you.
  19.                    ----->>>>     <<<<-----
  20.  
  21. 1. Files in the directory.
  22.  
  23.      README  .DOC   This document.
  24.      BACKGRND.DOC   Tutorial on some techniques used in these example
  25.                programs.
  26.  
  27.      COMPILER.H     Portability file to isolate compiler idiosyncrasies.
  28.      GREENHIL.H     Greenhills C version of COMPILER.H (plain vanilla).
  29.      IBMLATTI.H     IBM PC Lattice C 3.03 version of COMPILER.H.
  30.  
  31.      INTUALL .H     A super-include file for Amiga include files.
  32.  
  33.      REMALLOC.H     Header for RemAlloc subroutines.
  34.      REMALLOC.C     Memory ALLOCators which REMember the size allocated,
  35.                for simpler freeing.
  36.  
  37.      GIO     .H     Header file for Generic I/O speed up package.
  38.      GIO     .C     Generic I/O speed up routines (a disk cache).
  39.      GIOCALL .C     Outline of example GIO client.
  40.           To turn on the GIO package, change a switch in GIO.H,
  41.           add GIO.O to the linker control file, and recompile.
  42.  
  43.      IFF     .H     Header file for general IFF read/write support.
  44.      IFFR    .C     IFF reade support routines.
  45.      IFFW    .C     IFF writer support routines.
  46.           These routines do a lot of the work for reading and writing
  47.           IFF files robustly. The reader and writer are separate since
  48.           some programs don't need both.
  49.  
  50.      IFFCHECK.C     IFF checker utility source (very handy for debugging).
  51.      IFFCHECK.LNK   IFF checker utility linker control file.
  52.      IFFCHECK       Amiga runnable object program.
  53.           The IFF checker scans an IFF file, checks it for syntax
  54.           errors, and prints an outline of its contents.
  55.  
  56.      PACKER  .H     Header for byte run encoder (compressor) subroutines.
  57.      PACKER  .C     Run encoder subroutines.
  58.      UNPACKER.C     Run decoder subroutines.
  59.           This run encoder/decoder is used for ILBM raster images.
  60.  
  61.      ILBM    .H     Header for ILBM (raster image file) subroutines.
  62.      ILBMR   .C     ILBM reader support routines. Uses IFFR.
  63.      ILBMW   .C     ILBM writer support routines. Uses IFFW.
  64.  
  65.      READPICT.H     Header for ReadPicture subroutines.
  66.      READPICT.C     ReadPicture subroutines read an ILBM file into an
  67.                Amiga BitMap in RAM. Uses ILBMR and IFFR.
  68.  
  69.      SHOWILBM.C     Example program that reads and displays an ILBM file.
  70.      SHOWILBM.LNK   Linker control file for ShowILBM program.
  71.      SHOWILBM       Amiga runnable object program ShowILBM.
  72.      SHOWILBM.INFO  So you can run ShowILBM under the Amiga workbench.
  73.  
  74.      PUTPICT .H     Header for PutPict subroutines.
  75.      PUTPICT .C     PutPict subroutines write an Amiga BitMap from RAM
  76.                to an ILBM file. Uses ILBMW and IFFW.
  77.  
  78.      RAW2ILBM.C     Example program that reads a "raw" raster image file
  79.                and writes the image as an ILBM file.
  80.      RAW2ILBM.LNK   Linker control file for Raw2ILBM.
  81.      RAW2ILBM  Amiga runnable object program.
  82.  
  83.      ILBM2Raw.C     Example program that reads an image as an ILBM file
  84.                and writes the image as a "raw" raster image file.
  85.      ILBM2Raw.LNK   Linker control file for ILBM2Raw.
  86.      ILBM2Raw  Amiga runnable object program.
  87.  
  88.      BMPrintC.C     Subroutine that actually does the text dump.
  89.      ILBMDump.C     Example program that reads an image as an ILBM file
  90.                and writes the image as a text file containing
  91.                C data initialization statements for either a
  92.                BOB or a Sprite.
  93.      ILBMDump.LNK   Linker control file for ILBMDump.
  94.      ILBMDump  Amiga runnable object program.
  95.  
  96.      ZapIcon        Amiga runnable program that creates a tool icon from
  97.                an ILBM (i.e., a brush saved from DPaint).
  98.                Usage: zapicon brushname toolname
  99.  
  100.      IFFCHECG.LNK   Link file for IFFCheck including GIO.
  101.      SHOWILBG.LNK   Link file for ShowILBM including GIO.
  102.      RAW2ILBG.LNK   Link file for Raw2ILBM including GIO.
  103.  
  104.                -- All ".BAT" files are MS-DOS batch files --
  105.      COMPILE .BAT   Batch file to compile all the IFF source code.
  106.      LINK    .BAT   Batch file to link IFFCheck, ShowILBM, & Raw2ILBM.
  107.      LINKGIO .BAT   Batch file to link the 3 programs with GIO.
  108.  
  109.      SOURCE  .BAT   Batch file to copy/print/etc. all the source files.
  110.      NotSrc  .BAT   Batch file to copy/print/etc. all the other files.
  111.      RELEASE .BAT   Batch file to copy/print/etc. all the files.
  112.      AllIFFO .BAT   Combine iff primitives into one file alliff.o.
  113.  
  114.      startup .txt   Becomes s/Startup-Sequence on Amiga IFF disk.
  115.  
  116.      dragon         A picture of a dragon, in ILBM format.
  117.      dragon    .info     Amiga icon for dragon.
  118.      dragon    .c   Dragon as a BOB as C data statements, using ILBMDump.
  119.      mumbo     .info     Dragon as an icon for an imagined tool 'mumbo',
  120.                using ZapIcon.
  121.  
  122.      bird3to8  A picture containing frames # 3 thru 8 of a
  123.                flying eagle, in ILBM format.
  124.      bird3to8.lo3   A picture containing frames # 3 thru 8 of a
  125.                flying eagle, in RAW format, low-resolution,
  126.                3-bitplanes.
  127.      bird3to8.info  Amiga icon.
  128.      bird0to2  Frames # 0 thru 2 of flying eagle.
  129.      bird0to2.info  Amiga icon.
  130.  
  131. 2. About the development environment.
  132.  
  133. This source code is built for the Lattice 68000 C cross-compiler from the IBM
  134. PC and the MetaComCo Amiga linker. You may have to make changes to suit other
  135. development tools, another development machine, or another target machine.
  136.  
  137. These programs use C header files supplied by Commodore for the Amiga
  138. computer. If you need them, contact Commodore. Dependencies on the runtime
  139. environment are pretty localized, so ports should be easy.
  140.  
  141.  
  142. If you don't have Commodore's EXEC/TYPES.H file, here are some global IFF
  143. definitions you'll need:
  144.  
  145. typedef long        LONG;         /* signed   32-bit number */
  146. typedef unsigned long    ULONG;        /* unsigned 32-bit number */
  147. typedef short       WORD;         /* signed   16-bit number */
  148. typedef unsigned short   UWORD;        /* unsigned 16-bit number */
  149. typedef char        BYTE;         /* signed    8-bit number */
  150. typedef unsigned char    UBYTE;        /* unsigned  8-bit number */
  151. typedef short       BOOL;
  152. #define NULL        0
  153.  
  154.  
  155. 3. Compiler ideosyncracies.
  156.  
  157. The Lattice C compiler running on the IBM PC supports a recent addition to
  158. the C language: the ability to typecheck procedure arguments (templates).
  159. Believe me, typechecking is useful! The more bugs I find at compile time,
  160. the less I have to find at run time.
  161.  
  162. The programmer asks for this typechecking via an "extern" statement like this:
  163.      extern IFFP Seek(BPTR, LONG, LONG);
  164. or a "typedef" statement like this:
  165.      typedef IFFP ClientProc(struct _GroupContext *);
  166.  
  167. Unfortunately, this chokes other C compilers. If you have such a compiler,
  168. you have to comment out the stuff in parentheses. The above two examples
  169. become:
  170.      extern IFFP Seek(/* BPTR, LONG, LONG */);
  171. or a "typedef" statement like this:
  172.      typedef IFFP ClientProc(/* struct _GroupContext * */);
  173. Don't remove the parentheses!
  174.  
  175. The header file COMPILER.H defines macros to isolate the compiler
  176. dependencies. The macro FDwAT ("function definitions with argument
  177. types") switches on/off the argument type declarations in the header files
  178. in this directory.
  179.  
  180.  
  181. 4. RemAlloc subroutines.
  182.  
  183. The "REMembering ALLOCator" is a useful little subroutine package included
  184. here. It saves you from having to remember the size of each node you
  185. allocate. (Why doesn't the Amiga allocator do this?)
  186.  
  187.  
  188. 5. Optional buffered file I/O package GIO.
  189.  
  190. Amiga file I/O can be greatly sped up by use of a RAM buffer. So we now have
  191. a layer of software that provides optional buffering. The "option" is
  192. controlled by changing a "#define" inside the header file GIO.H, adding
  193. GIO.O to your link file, recompiling, and recompiling. When turned off,
  194. this layer becomes just a layer of macro calls between the IFFR and IFFW
  195. modules and the AmigaDOS routines they call.
  196.  
  197. This RAM buffer speeds things up when you're doing numerous small Writes
  198. and/or Seeks while writing. The general IFF writer IFFW.C tends to do this.
  199. It should be extended to optimize reading, too.
  200.  
  201. If you are not using IFF, and already Write in chunks of 256 bytes or more,
  202. don't bother using GIO.
  203.  
  204.